The X-Philes (2nd Revision)/The X-Philes Number 1 (1995).iso/xphiles/hp48hor2/suite3d.doc

Text File | 1995-03-31 | 21KB | 477 lines

(Comp.sources.hp48) Main: r
  Subj: v03i003:  suite3d - 3d Graphing Suite v3.0, Part01/02
Author: [Charles Patton]
Item: 23 by charliep at hpcvrs.cv.hp.com
  Date: Mon Dec 02 1991 17:28

@ Version 3.0 @

_Introduction_

     The programs contained in this document comprise a suite of 3D
graphing/viewing utilities for the HP-48 (an HP-28 version will be
forthcoming provided sufficient interest.)

     We had several requirements to consider in creating these
programs. Our aims were that they be (1) purely user code, (2)
relatively short, and (3) psychologically effective.  Aims (1) and (2)
are due to our target audience of educators, many of whom have little
contact with technology beyond their use of the HP-48 or HP-28. We
expect that, in many situations, one user will obtain the code in
printed form, enter it into their machine, and transmit it to others
via the infrared I/O.

     In exploring visualization techniques on a variety of machines we
found that increasing "realism" (read: ray-traced, Phong-shaded,
hidden-line, etc.) in the graphical presentation of functions of two
variables did not necessarily correlate with increasing ease of
comprehension. These programs represent the results of some of these
experiments (including time-to-completion as an important factor).

     We invite you to try them out and experiment yourself. All
suggestions, additions, corrections, insights, commentary, and
criticisms are welcome.

_Suite3D Version 3.0 Additions and Changes_

Version 3.0 adds one new feature, GRIDMAP, which presents a method
of visualizing maps from the plane to the plane. The idea is simple:
draw the image under the mapping function of a rectilinear grid residing
in the input plane. Besides being used in various graphing programs, such
as 'f(z)' by Lascoux Graphics, it has been shown to be an effective aid
in understanding iterated maps of the plane (see "Grid Imaging for a Two-
Dimensional Map," Judd, Mees, Aihara, and Toyada, _International Journal
of Bifurcation and Chaos_, V1 N1, March 1991.)

As usual, POSTSCRIPT output capabilites for this plotting method are
included and, as usual, you can leave them out if you are short on
room.

_Suite3D Version 2.0 Additions and Changes_

In addition to the slopefield, pseudo-contour, oblique perspective,
Phong-Shaded, and movie plotting capabilities, version 2.0 introduces

*Major Feature*  POSTSCRIPT(TM) output for all the graphing routines in a
form suitable for editing/viewing with Adobe Illustrator(TM), sending to a
POSTSCRIPT printer, or including in a \special {\illustration} TeX(TM)
command. Included is a PS-output version of the standard DRAW command.

All the output is in terms of line segments, Bezier curves, and fill-
regions so that it can be scaled to arbitrary size or printed at
very high resolution without loss of smoothness.

If you have ever wanted to produce high-quality function-graph illustrations
with the flexibility that '48 provides, this is for you! (You might be able
to tell that I'm pretty happy with this item.)

*Significant Addition* (relatively) fast WIREFRAME graphing in oblique
3D perspective with adjustable grid spacing.

*Easier View Switching* The 3D plotting parameters have been rearranged
so that all the routines can compute an appropriate XRNG and YRNG from
these. Once set, you can go from view to view with no manual adjustments.

*Other Enhancements*
   A Movie single-step has been added so that you can easily step through a
   Movie frame-by-frame.

   All routines now use user-specified number of X-increments and
Y-increments,
   as appropriate, so that the WIREFRAME grid, the lattice of slopefield
   segements, and number of Movie frames, etc. all references these numbers
   rather than being "hard coded" as in the earlier versions.

_NO WARRANTY_
    This work is provided on an "as is" basis. Hewlett-Packard Co.
provides no warranty whatsoever, either express or implied regarding
the work, including warranties with respect to its merchantability or
fitness for any purpose whatsoever.

_Copyright_
   Copyright (C), 1991, Hewlett-Packard Co. Permission to copy all or
part of this work is granted provided that the copies are not made or
distributed for resale (excepting nominal copying fees) and the
 _NO WARRANTY_ and this copyright notice are included verbatim. Other
permissions can be arranged by contacting the author.

_Correspondence_

Correspondence on Suite3D suite should be sent to Charles Patton at one of the
following addresses:

snail-mail:
          M.S. 5U-L9
          Hewlett-Packard Co.
          1000 N.E. Circle Blvd.
          Corvallis, OR 97330

e-mail:
          [e-mail]    (for Internet hosts)
          hplabs!hpcvrs!charliep (for UUCP hosts)

_Organization_

     Analogous to the built-in plotting routines, all the Suite3D
programs assume that the function of interest is stored in EQ.
Further, they assume that the function is represented as an expression
in the variables 'X' and 'Y' (e.g. u,v -> sin(u+v) is represented as
'SIN(X+Y)' in EQ).

N.B.> Insure that 'X' and 'Y' are formal (no variables 'X' and 'Y'
N.B.> along the current path).

N.B.> Most of these routines produce their best-looking output with the
N.B.> machine in "CONNECT" mode ( the CNCT button in the MODES menu
N.B.> toggles this mode.)

N.B.> While you are examining the MODES menu, be sure to check that the
N.B.> the machine is in SYMBOLIC EVALUATION mode ( SYM button.)

     The viewing region and other Suite3D plotting parameters are stored
in the sub-directory, VPAR. VPAR contains the variables:
    Xleft and Xright,
       controlling the width of the view-volume,
    Yfar and Ynear,
       controlling the depth of the view-volume,
    Zlow and Zhigh,
       controlling the height of the view volume,
    XXleft and XXright,
       controlling the horizontal range of the GRIDMAP
       output plane,
    YYlow and YYhigh,
       controlling the vertical range of the GRIDMAP
       output plane,
    Xe, Ye, and Ze,
       the coordinates of the eye-point,
    Nx and Ny,
       the number of X- and Y-increments desired, and
    hidden
       the flag indicating that hidden-line plotting should be used
       in the Yview plotter.

      VPAR was implemented as a sub-directory so that the REVIEW key can be
used to examine the state of these variables in a way which reminds
the user of their meaning.

     Other than VPAR, the programs here are organized into a single
directory for convenience.  Inter-dependence of the programs and other
variables is noted in the program description.

_Oversized PICTs_

     All of the programs seem to work reasonably well with arbitrary sized
PICT grobs. However, ShapeToShade only draws to the upper-left-hand-corner
of the grob, and Movie only shows the display-sized region of the grob (what
else could it do?) The POSTSCRIPT plotting routines scale their results to
the size of the default PICT grob, but this should pose few problems.

_Descriptions of the Programs_

SlopeField:
     The SlopeField program plots a lattice of line segments whose
slopes represent the function value at their centerpoint. Using
SlopeField to plot F(X,Y) allows your eye to pick out integral curves
of the differential equation dy/dx=F(x,y). It is quite useful in
understanding where the "arbitrary constant" in anti-derivatives comes
from.

The number of lattice points per row is determined by Nx and the
number of lattice points per column is determined by Ny. The input region
sampled is given by Xleft < X < Xright and Ynear < Y < Yfar.

psContour:
     The psContour program (pseudo-contour) program uses SlopeField to
produce a fast contour plot of the current function. By plotting the
direction field perpendicular to the gradient of the function it
allows your eye to pick out the integral curves (contours) without
actually plotting them. The apparent contours are evenly spaced
visually and so give no information on how steep the graph is at any
particular point.

The number of lattice points per row is determined by Nx and the
number of lattice points per column is determined by Ny. The input region
sampled is given by Xleft < X < Xright and Ynear < Y < Yfar.

YView:
     The YView program provides an oblique-view, perspective, 3D
surface plot (viewing toward increasing Y). This produces a sequence of
plots of the function along Y=constant lines in the input domain. These
plots are perspective-projected onto the view-plane relative to the eye
point. In overhead view:
                                Yfar
       +----------------+
 .     |            |  .
       |            |
 Xleft |      /\    |Xright
    .  |     /  \       | .
     . |     .   .      |.
       +----------------+
       .      .  .      . Ynear
          .      .       .
            .     . .    .
   ---------.----..---.--------------------- view-plane
                 .  .   .
                     . . .
                       *  eye-point (Xe,Ye,Ze)
             |<- XRNG ->|

     The same picture holds with Zlow replacing Xleft, Zhigh replacing Xright,
and YRNG replacing XRNG (and turning your head 90 degrees to the right.)

     In short, Ynear and Yfar and Ny determine the Y-inputs sampled;
Xleft, Xright, and the eye-point determine the XRNG; Zlow, Zhigh,
and the eye-point determine the YRNG. This computation is performed by
the utility, SetWindow.

     This is a simple "divide-by-depth" method for perspective
plotting where the viewplane is always 1 unit from the viewpoint and
is parallel to the x-z plane. Since the perspective transformation in
the case can be implemented by a simple change of coordinates,
plotting individual sections is no slower than ordinary plots.

     If 'hidden' is non-zero, each plot of a sampled point will erase the
column of pixels below it. Since the curves are plotted back-to-front,
this results in a hidden-line plot of the surface. It works best if
RES is #1 or #2 and connected-mode is on (CNCT.)

     Note: To abort this routine, press the [ON] key and then press
the [ENTER] key.

WIREFRAME:
     The WIREFRAME program plots an oblique-perspective view of a wire-frame
model of the surface with Nx vertices in each row and Ny vertices in each
column. It calls SetWindow to set the XRNG and YRNG and uses much the same
technique as Yview. The sampled region is determined by Xleft, Xright, Ynear,
and Yfar.

ShapeToShade:
     The ShapeToShade program plots the function as a Phong-shaded
figure viewed from above with a light source from above, that
is, shaded according to the angle the tangent plane makes with the incident
light source. It assumes that the variable DPAR contains sixteen 4x4 GROBS
to serve as the dithering pattern. The dither patterns included are probably
not the best possible: insights along these lines are most welcome. The
variables Xleft, Xright, Yfar, and Ynear determine the inputs sampled.

Movie:
     The Movie program plots Ny cross-sections of the function plot
varying the Y-value from Yfar to Ynear. The viewing window is determined
by Xleft, Xright, Zlow, and Zhigh. Having plotted these frames, it calls the
utility program, uSMOV (utility-show-movie), to play them  back in
repeated sequence.

     Note: To abort this routine in the plotting phase, press the [ON]
key and then press the [ENTER] key.  To end the movie press any key
(e.g. [ENTER]).

uSMOV:
     The uSMOV (utility show-movie) program takes an alternating sequence of
<n> grobs and <n> descriptors (with <2n> on the top of the stack) from the
stack and shows them in sequence, thus producing a movie effect. Stop
the show with any key press but [ON].

SSTMovie:
     After stopping Movie or uSMOV, you can use SSTMovie to step through
the sequence of movie frames. To show the next frame, press any key but
[ENTER] or [ON]. Press [ENTER] to quit.

GRIDMAP:
     The GRIDMAP routine takes a complex valued function (stored in EQ
as a complex-valued expression in X and Y) and plots the image under
this map of a rectilinear grid with Nx columns and Ny rows which lives
in the region [Xleft,Xright]x[Ynear,Yfar]. The portion of the output
plane shown on the screen is [XXleft,XXright]x[YYlow,YYhigh]. These
are additional variables in VPAR. The trig and arc-trig functions
(e.g. 'SIN(X+i*Y)') give very interesting "starter" examples.

     To get the image of a polar grid rather than a rectilinear grid,
precompose you function with the polar-to-rectangular coordinate
change:
  'SIN(X+i*Y)' {X 'X*COS(Y)' Y 'X*SIN(Y)'} |
=> 'SIN(X*COS(Y)+i*X*SIN(Y))'

     Setting 'Xleft' to 0 and 'Xright' to 1 then corresponds to
setting (the nonexistent) 'Rlow' to 0 and 'Rhigh' to 1. Similarly,
settign 'Ynear' to 0 and 'Yfar' to 2pi corresponds to setting the
angular range.

SetWindow:
    This utility maps the view volume and eye-point coordinates into the
appropriate XRNG and YRNG values for perspective plotting (see the picture
in the YView description.) It also gets all the plotting parameters onto
the stack.

_The POSTSCRIPT Drawing Utilities_

     Since the PS utilities take up a fair amount of space, and are not of
immediate use to someone without Adobe Illustrator and/or a POSTSCRIPT
printer, all of the above programs have been designed to work properly
even if the PS utility set is not installed. If this is your situation,
simply delete the section of the Suite3D listing starting at the comment,
@ Begin POSTSCRIPT Stuff @, before you send the file to the '48, otherwise,
read on.

When POSTSCRIPT Output Mode is switched on (using PSTOGGLE,) all of the
plotting routines above will, in addition to their normal function,
accumulate POSTSCRIPT commands corresponding to what they were attempting
to plot on the '48 display. These are saved in a sequence of variables,
PSOUT, PSOUT&, PSOUT&&, etc. Although the output is simply ASCII text
saved as '48 character strings, it is broken up into at-most-4Kbyte
chunks so that it is easier to handle on the '48. When this text is
inserted into a "boilerplate" file (described below) the resulting
file can be sent to a POSTSCRIPT printer, or edited/viewed in the
Adobe Illustrator, or compatible, POSTSCRIPT Drawing program.

_Descriptions of the User-intended Programs__

PSTOGGLE:
     When executed, this routine switches between normal (no-PS output)
and PS-output definitions of the basic graphics routines (that is, draw,
line, and tile) used in the other Suite3D programs. The new state ("PS is ON"
or "PS is OFF") is displayed on completion of the routine.

PSRESET:
    This routine should be used to simply clear any leftover data in the
output variables PSOUT, PSOUT&, etc. making room for a new run.

_Using the PS Capabilities_

  _The Boilerplate File_
    To effectively use the PS output from the '48 you need to have a
"boilerplate" POSTSCRIPT file in which you can insert your '48 output
(it can even reside on the '48 if you have room .. in this case you
can have your '48 talk directly to a POSTSCRIPT printer ..) The
easiest way to get one is to create a new illustration in Illustrator
with no actual drawing but with the Fill set to NONE, the Line Width
set to, say, .5, and the Line Color set to 100% BLACK.  Save this as a
POSTSCRIPT (i.e. text) file HP48PS.ai or some such name.

Open the resulting file with a text editor so you can see what it looks like.
There are two regions of interest. The first is the line near the top of the
file that looks like

%%BoundingBox:x1 y1 x2 y2

where x1, x2, y1, and y2 are integers. You should change these to

%%BoundingBox:0 0 131 64

While this is not strictly necessary, it will allow you to include the '48
produced illustration directly in a TeX document an have the size computed
correctly.

The next region of interest is  near the end of file and begins with

%%Note:

and ends with

%%Trailer

Clear out anything between these two (this is the region where the '48
output will be inserted) and save the resulting file. This will be your
"boilerplate" file.

  _Creating the Output_
     This part is quite easy. After you have found a nice view with one of
the graphing utilities (with PS output turned off to speed things up) set the
RES quite high ( #13d RES [ENTER] will do nicely ) and numeric display
format quite small ( 2 FIX [ENTER] seems pretty good ) to save on room, use
PSRESET to clear the variables (if you want to get rid of a previous session)
and PSTOGGLE to activate PS mode. Now re-active the chosen plotting routine
and let it finish.

When it is finished, transfer the contents of all the non-empty PSOUT
variables
(in ASCII mode, please) in order (PSOUT, PSOUT&, PSOUT&&, etc.) into the
region
of the boilerplate file noted above. Save the resulting file under a new name
(to preserve your boilerplate file) and you are ready to send it to a
POSTSCRIPT
printer, include it in a TeX, or muck around with it in a POSTSCRIPT drawing
program.

  _RAM Requirements, etc._
     The routines require very different amounts of RAM (corresponding
directly
with the output size.) A reasonable psContour results in under 4K of output
while a ShapeToShade can result in nearly 40K of output. The other routines
fall between these two (with reasonable settings for Nx, Ny, RES, and FIX.)
If desired, one could modify the PSADDTO routine (see below) to simply send
accumulated data out over one of the datacomm ports thus passing off the space
requirements to the machine at the other end of the line.

  _What's Been Tried_
     I've used the PS output in the form discussed above with equally good
results in Illustrator88 on a Mac IIx, direct printing to an Apple
LaserWriter,
in a Textures TeX file, and in Adobe Illustrator 1.1 under  Windows 3.0.

POSTSCRIPT, Adobe Illustrator, and Illustrator88 are trademarks of Adobe
Systems
Corporation;
Textures is a trademark of Blue Sky Research, Inc.;
Apple LaserWriter is a trademark of Apple Computer, Inc.;
Windows is a trademark of MicroSoft Corporation;
TeX is a trademark of the American Mathematical Society.

_Descriptions of the Utilities_

PSTILE:
    This utility takes a screen location (as #pixel_row #pixel_column)
followed by two unused parameters and a gray-scale value in the range [0,1],
returns these unchanged to the stack and outputs the PS code to draw a
filled-in 4x4 square at the corresponding location and with the corresponding
gray-scale fill.

PSADDTO:
   This utility takes a string off the stack and adds it to the current
PS output variable, checking for overflow of the 4000 character limit
and starting a new output variable if the limit is exceeded.

PSDRAW:
   Draws the current EQ (assumed to be a single expression) and outputs
a PS representation of the curve drawn as a connected sequence of Bezier
curves. It assumes that the plot type is currently FUNCTION.

PSPARDRAW
  Draws the current EQ (assumed to be a single expression) and outputs
a PS representation of the curve drawn as a connected sequence of
Bezier curves. It assumes that the plot type is currently PARAMETRIC.

PSLINE:
  Takes a pair of complex numbers representing the endpoints of a line,
draws the line on the screen and outputs the corresponding PS line drawing
command.

CURRENTOUT:
  A variable containing the name of the current PS output variable
('PSOUT', 'PSOUT&', 'PSOUT&&', etc.)

PSCO:
  Takes a complex number and returns, as a string, the corresponding
PS coordinate value.

PSCOPAIR:
  Takes a pair of complex numbers representing the third and fourth of
four Bezier curve control points and returns these as a string representing
the PS cross-over sequence of a Bezier curve.

derFP
  A definition of the derivative of the FP function suitable for
supporting the PS drawing in GRIDMAP.

derIP
  A definition of the derivative of the IP function suitable for
supporting the PS drawing in GRIDMAP.

derIM
  A definition of the derivative of the IM function suitable for
supporting the PS drawing in GRIDMAP.

derRE
  A definition of the derivative of the RE function suitable for
supporting the PS drawing in GRIDMAP.